for #8

Algorithm:

Function dirmap takes: 


• starting directory (relative or absolute)

• function to filter by

• boolean for recursion (defaults to true)

• maximum depth (defaults to unlimited)
• boolean for following symlinks (defaults to false)

It returns an array of files for which the filter function returns true.

Function _traverse is a recursive helper function that takes:

• 
current directory (absolute)
• 
filter function
• 
recursion boolean
• 
current depth
• 
max depth
• boolean for following symlinks

• reference to a results array


It does not return a value, but rather pushes to the results array that it was given a reference to.

If a relative path is provided, dirmap finds the absolute path.

dirmap then passes the found absolute path for the start directory, the filter function, the recursion boolean, a 0 for current depth, the max depth, the symlinks boolean, and a reference to the found_files array (via @found_files) to _traverse.

_traverse opens the start directory and enters a while loop.

While unchecked entries exist in the directory:
skip . (current directory) and .. (previous directory)
find the absolute path of the current entry
if entry is not a symlink or symlink following is allowed:

• if entry is a directory and recursion is enabled, call _traverse (recursive call), passing in the current entry’s absolute path and adding 1 to the current depth
• if entry is a file and the filter function returns true (via $filter_func->($abs_path_to_entry)), push the full path to the results array

Once the while loop completes, the directory is closed.
_traverse returns immediately if the current depth ever exceeds the max depth, immediately unraveling the recursion.

Once _traverse completes recursion, dirmap returns the array of matching files.